<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Nested datatype | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="mapping-types.html" title="Field datatypes">
<link rel="prev" href="keyword.html" title="Keyword datatype">
<link rel="next" href="number.html" title="Numeric datatypes">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="mapping.html">Mapping</a></span>
»
<span class="breadcrumb-link"><a href="mapping-types.html">Field datatypes</a></span>
»
<span class="breadcrumb-node">Nested datatype</span>
</div>
<div class="navheader">
<span class="prev">
<a href="keyword.html">« Keyword datatype</a>
</span>
<span class="next">
<a href="number.html">Numeric datatypes »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="nested"></a>Nested datatype<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/nested.asciidoc">edit</a>
</h2>
</div></div></div>

<p>The <code class="literal">nested</code> type is a specialised version of the <a class="xref" href="object.html" title="Object datatype"><code class="literal">object</code></a> datatype
that allows arrays of objects to be indexed in a way that they can be queried
independently of each other.</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>When ingesting key-value pairs with a large, arbitrary set of keys, you might consider modeling each key-value pair as its own nested document with <code class="literal">key</code> and <code class="literal">value</code> fields. Instead, consider using the <a class="xref" href="flattened.html" title="Flattened datatype">flattened</a> datatype, which maps an entire object as a single field and allows for simple searches over its contents.
Nested documents and queries are typically expensive, so using the <code class="literal">flattened</code> datatype for this use case is a better option.</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="nested-arrays-flattening-objects"></a>How arrays of objects are flattened<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/nested.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Elasticsearch has no concept of inner objects. Therefore, it flattens object
hierarchies into a simple list of field names and values. For instance, consider the
following document:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT my_index/_doc/1
{
  "group" : "fans",
  "user" : [ <a id="CO306-1"></a><i class="conum" data-value="1"></i>
    {
      "first" : "John",
      "last" :  "Smith"
    },
    {
      "first" : "Alice",
      "last" :  "White"
    }
  ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/671.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO306-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">user</code> field is dynamically added as a field of type <code class="literal">object</code>.</p>
</td>
</tr>
</table>
</div>
<p>The previous document would be transformed internally into a document that looks more like this:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">{
  "group" :        "fans",
  "user.first" : [ "alice", "john" ],
  "user.last" :  [ "smith", "white" ]
}</pre>
</div>
<p>The <code class="literal">user.first</code> and <code class="literal">user.last</code> fields are flattened into multi-value fields,
and the association between <code class="literal">alice</code> and <code class="literal">white</code> is lost.  This document would
incorrectly match a query for <code class="literal">alice AND smith</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET my_index/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "user.first": "Alice" }},
        { "match": { "user.last":  "Smith" }}
      ]
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/672.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="nested-fields-array-objects"></a>Using <code class="literal">nested</code> fields for arrays of objects<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/nested.asciidoc">edit</a>
</h3>
</div></div></div>
<p>If you need to index arrays of objects and to maintain the independence of
each object in the array, use the <code class="literal">nested</code> datatype instead of the
<a class="xref" href="object.html" title="Object datatype"><code class="literal">object</code></a> datatype.</p>
<p>Internally, nested objects index each object in
the array as a separate hidden document, meaning that each nested object can be
queried independently of the others with the <a class="xref" href="query-dsl-nested-query.html" title="Nested query"><code class="literal">nested</code> query</a>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT my_index
{
  "mappings": {
    "properties": {
      "user": {
        "type": "nested" <a id="CO307-1"></a><i class="conum" data-value="1"></i>
      }
    }
  }
}

PUT my_index/_doc/1
{
  "group" : "fans",
  "user" : [
    {
      "first" : "John",
      "last" :  "Smith"
    },
    {
      "first" : "Alice",
      "last" :  "White"
    }
  ]
}

GET my_index/_search
{
  "query": {
    "nested": {
      "path": "user",
      "query": {
        "bool": {
          "must": [
            { "match": { "user.first": "Alice" }},
            { "match": { "user.last":  "Smith" }} <a id="CO307-2"></a><i class="conum" data-value="2"></i>
          ]
        }
      }
    }
  }
}

GET my_index/_search
{
  "query": {
    "nested": {
      "path": "user",
      "query": {
        "bool": {
          "must": [
            { "match": { "user.first": "Alice" }},
            { "match": { "user.last":  "White" }} <a id="CO307-3"></a><i class="conum" data-value="3"></i>
          ]
        }
      },
      "inner_hits": { <a id="CO307-4"></a><i class="conum" data-value="4"></i>
        "highlight": {
          "fields": {
            "user.first": {}
          }
        }
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/673.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO307-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The <code class="literal">user</code> field is mapped as type <code class="literal">nested</code> instead of type <code class="literal">object</code>.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO307-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>This query doesn’t match because <code class="literal">Alice</code> and <code class="literal">Smith</code> are not in the same nested object.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO307-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>This query matches because <code class="literal">Alice</code> and <code class="literal">White</code> are in the same nested object.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO307-4"><i class="conum" data-value="4"></i></a></p>
</td>
<td align="left" valign="top">
<p><code class="literal">inner_hits</code> allow us to highlight the matching nested documents.</p>
</td>
</tr>
</table>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="nested-accessing-documents"></a>Interacting with <code class="literal">nested</code> documents<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/nested.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Nested documents can be:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
queried with the <a class="xref" href="query-dsl-nested-query.html" title="Nested query"><code class="literal">nested</code></a> query.
</li>
<li class="listitem">
analyzed with the <a class="xref" href="search-aggregations-bucket-nested-aggregation.html" title="Nested Aggregation"><code class="literal">nested</code></a>
and <a class="xref" href="search-aggregations-bucket-reverse-nested-aggregation.html" title="Reverse nested Aggregation"><code class="literal">reverse_nested</code></a>
aggregations.
</li>
<li class="listitem">
sorted with <a class="xref" href="search-request-body.html#nested-sorting" title="Sorting within nested objects.">nested sorting</a>.
</li>
<li class="listitem">
retrieved and highlighted with <a class="xref" href="search-request-body.html#nested-inner-hits" title="Nested inner hits">nested inner hits</a>.
</li>
</ul>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>Because nested documents are indexed as separate documents, they can only be
accessed  within the scope of the <code class="literal">nested</code> query, the
<code class="literal">nested</code>/<code class="literal">reverse_nested</code> aggregations, or <a class="xref" href="search-request-body.html#nested-inner-hits" title="Nested inner hits">nested inner hits</a>.</p>
<p>For instance, if a string field within a nested document has
<a class="xref" href="index-options.html" title="index_options"><code class="literal">index_options</code></a> set to <code class="literal">offsets</code> to allow use of the postings
during the highlighting, these offsets will not be available during the main highlighting
phase.  Instead, highlighting needs to be performed via
<a class="xref" href="search-request-body.html#nested-inner-hits" title="Nested inner hits">nested inner hits</a>. The same consideration applies when loading
fields during a search through <a class="xref" href="run-a-search.html#docvalue-fields" title="Doc value fields"><code class="literal">docvalue_fields</code></a> or <a class="xref" href="search-request-body.html#request-body-search-stored-fields" title="Stored Fields"><code class="literal">stored_fields</code></a>.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="nested-params"></a>Parameters for <code class="literal">nested</code> fields<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/nested.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following parameters are accepted by <code class="literal">nested</code> fields:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<a class="xref" href="dynamic.html" title="dynamic"><code class="literal">dynamic</code></a>
</span>
</dt>
<dd>
(Optional, string)
Whether or not new <code class="literal">properties</code> should be added dynamically to an existing
nested object.  Accepts <code class="literal">true</code> (default), <code class="literal">false</code> and <code class="literal">strict</code>.
</dd>
<dt>
<span class="term">
<a class="xref" href="properties.html" title="properties"><code class="literal">properties</code></a>
</span>
</dt>
<dd>
(Optional, object)
The fields within the nested object, which can be of any
<a class="xref" href="mapping-types.html" title="Field datatypes">datatype</a>, including <code class="literal">nested</code>. New properties
may be added to an existing nested object.
</dd>
<dt>
<span class="term">
<code class="literal">include_in_parent</code>
</span>
</dt>
<dd>
(Optional, boolean)
If <code class="literal">true</code>, all fields in the nested object are also added to the parent document
as standard (flat) fields. Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">include_in_root</code>
</span>
</dt>
<dd>
(Optional, boolean)
If <code class="literal">true</code>, all fields in the nested object are also added to the root
document as standard (flat) fields. Defaults to <code class="literal">false</code>.
</dd>
</dl>
</div>
<h3>
<a id="_limits_on_nested_mappings_and_objects"></a>Limits on <code class="literal">nested</code> mappings and objects<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/mapping/types/nested.asciidoc">edit</a>
</h3>
<p>As described earlier, each nested object is indexed as a separate Lucene document.
Continuing with the previous example, if we indexed a single document containing 100 <code class="literal">user</code> objects,
then 101 Lucene documents would be created: one for the parent document, and one for each
nested object. Because of the expense associated with <code class="literal">nested</code> mappings, Elasticsearch puts
settings in place to guard against performance problems:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">index.mapping.nested_fields.limit</code>
</span>
</dt>
<dd>
The maximum number of distinct <code class="literal">nested</code> mappings in an index. The <code class="literal">nested</code> type should only be used in special cases, when arrays of objects need to be queried independently of each other. To safeguard against poorly designed mappings, this setting
limits the number of unique <code class="literal">nested</code> types per index. Default is <code class="literal">50</code>.
</dd>
</dl>
</div>
<p>In the previous example, the <code class="literal">user</code> mapping would count as only 1 towards this limit.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">index.mapping.nested_objects.limit</code>
</span>
</dt>
<dd>
The maximum number of nested JSON objects that a single document can contain across all
<code class="literal">nested</code> types. This limit helps to prevent out of memory errors when a document contains too many nested
objects. Default is <code class="literal">10000</code>.
</dd>
</dl>
</div>
<p>To illustrate how this setting works, consider adding another <code class="literal">nested</code> type called <code class="literal">comments</code>
to the previous example mapping. For each document, the combined number of <code class="literal">user</code> and <code class="literal">comment</code>
objects it contains must be below the limit.</p>
<p>See <a class="xref" href="mapping.html#mapping-limit-settings" title="Settings to prevent mappings explosion">Settings to prevent mappings explosion</a> regarding additional settings for preventing mappings explosion.</p>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="keyword.html">« Keyword datatype</a>
</span>
<span class="next">
<a href="number.html">Numeric datatypes »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
